{smcl}
{* *! version 1.0.0  30sep2016}{...}
{viewerdialog merge "dialog merge2"}{...}
{vieweralsosee "[D] merge2" "mansection D merge2"}{...}
{vieweralsosee "" "--"}{...}
{vieweralsosee "[D] merge" "help merge"}{...}
{vieweralsosee "[D] append" "help append"}{...}
{vieweralsosee "[D] cross" "help cross"}{...}
{vieweralsosee "[D] joinby" "help joinby"}{...}
{vieweralsosee "[D] save" "help save"}{...}
{vieweralsosee "[D] sort" "help sort"}{...}
{viewerjumpto "Syntax" "merge2##syntax"}{...}
{viewerjumpto "Description" "merge2##description"}{...}
{viewerjumpto "Options" "merge2##options"}{...}
{viewerjumpto "Examples" "merge2##examples"}{...}
{title:Title}

{p2colset 5 20 20 2}{...}
{p2col :{manlink D merge2} {hline 2}}Generalized merge{p_end}
{p2colreset}{...}


{marker syntax}{...}
{title:Syntax}

{pstd}
One-to-one merge on specified key variables, where key variable names are the same in both datasets

{p 8 15 2}
{opt mer:ge2} {cmd:1:1} {varlist} 
{cmd:using} {it:{help filename}} [{cmd:,} {it:options}]

{pstd}
One-to-one merge on specified key variables, where key variables have different names in master and using

{p 8 15 2}
{opt mer:ge2} {cmd:1:1} {varlist} 
{cmd:using} {it:{help filename}}, {cmd:using_keys}({varlist}) [{it:options}]


{pstd}
Many-to-one merge on specified key variables, where key variable names are the same in both datasets

{p 8 15 2}
{opt mer:ge2} {cmd:m:1} {varlist} 
{cmd:using} {it:{help filename}} [{cmd:,} {it:options}]

{pstd}
Many-to-one merge on specified key variables, where key variables have different names in master and using

{p 8 15 2}
{opt mer:ge2} {cmd:m:1} {varlist} 
{cmd:using} {it:{help filename}}, {cmd:using_keys}({varlist}) [{it:options}]


{pstd}
One-to-many merge on specified key variables, where key variable names are the same in both datasets

{p 8 15 2}
{opt mer:ge2} {cmd:1:m} {varlist} 
{cmd:using} {it:{help filename}} [{cmd:,} {it:options}]

{pstd}
One-to-many merge on specified key variables, where key variables have different names in master and using

{p 8 15 2}
{opt mer:ge2} {cmd:1:m} {varlist} 
{cmd:using} {it:{help filename}}, {cmd:using_keys}({varlist}) [{it:options}]


{pstd}
Many-to-many merge on specified key variables, where key variable names are the same in both datasets

{p 8 15 2}
{opt mer:ge2} {cmd:m:m} {varlist} 
{cmd:using} {it:{help filename}} [{cmd:,} {it:options}]

{pstd}
Many-to-many merge on specified key variables, where key variables have different names in master and using

{p 8 15 2}
{opt mer:ge2} {cmd:m:m} {varlist} 
{cmd:using} {it:{help filename}}, {cmd:using_keys}({varlist}) [{it:options}]

{pstd}
One-to-one merge by observation

{p 8 15 2}
{opt mer:ge2} {cmd:1:1 _n}
{cmd:using} {it:{help filename}} [{cmd:,} {it:options}]


{synoptset 20 tabbed}{...}
{synopthdr}
{synoptline}
{syntab :Options}
{synopt :{opth using_keys(varlist)}}variable names of keys in using dataset;
     default is the same as the master keys
{p_end}
{...}
{synopt :{opth keepus:ing(varlist)}}variables to keep from using data;
     default is all
{p_end}
{...}
{synopt :{opth gen:erate(newvar)}}name of new variable to mark merge
      results; default is {cmd:_merge}
{p_end}
{...}
{synopt :{opt nogen:erate}}do not create {cmd:_merge} variable
{p_end}
{...}
{synopt :{opt nol:abel}}do not copy value-label definitions from using{p_end}
{...}
{synopt :{opt nonote:s}}do not copy notes from using{p_end}
{...}
{synopt :{opt update}}update missing values of same-named variables in master
     with values from using
{p_end}
{...}
{synopt :{opt replace}}replace all values of same-named variables in master
     with nonmissing values from using (requires {cmd:update})
{p_end}
{...}
{synopt :{opt norep:ort}}do not display match result summary table
{p_end}
{synopt :{opt force}}allow string/numeric variable type mismatch without error
{p_end}

{syntab: Results}
{synopt :{cmd:assert(}{help merge##results:{it:results}}{cmd:)}}specify required match results
{p_end}
{...}
{synopt :{cmd:keep(}{help merge##results:{it:results}}{cmd:)}}specify which match results to keep
{p_end}
{...}

{synopt :{opt sorted}}do not sort; datasets already sorted
{p_end}
{...}
{synoptline}
{p2colreset}{...}
{p 4 6 2}
{opt sorted} does not appear in the dialog box.{p_end}


{marker description}{...}
{title:Description}

{pstd}
{cmd:merge2} generalizes the functionality of {cmd:merge} to allow {cmd:using} datasets
of non-DTA filetypes (currently, only CSVs are supported) and to allow variable key names
to vary across the master and using datasets. Without specifying the using_keys(varlist) option,
merge2 functions exactly the same as {cmd:merge}.

{pstd}
If {it:filename} is specified without an extension, then {cmd:.dta} is assumed. 


{marker options}{...}
{title:Options}

{dlgtab:Options}

{phang}
{opth keepusing(varlist)}
    specifies the variables from the using dataset that are kept
    in the merged dataset. By default, all variables are kept. 
    For example, if your using dataset contains 2,000
    demographic characteristics but you want only
    {cmd:sex} and {cmd:age}, then type {cmd:merge} ...{cmd:,}
    {cmd:keepusing(sex} {cmd:age)} ....

{phang}
{opth generate(newvar)} specifies that the variable containing match
      {help merge2##results:results} information should be named {it:newvar}
      rather than {cmd:_merge}.

{phang}
{cmd:nogenerate} specifies that {cmd:_merge} not be created.  This
    would be useful if you also specified {cmd:keep(match)}, because
    {cmd:keep(match)} ensures that all values of {cmd:_merge} would be 3.

{phang}
{cmd:nolabel}
    specifies that value-label definitions from the using file be ignored.
    This option should be rare, because definitions from the master are
    already used.

{phang}
{cmd:nonotes}
    specifies that notes in the using dataset not be added to the 
    merged dataset; see {manhelp notes D:notes}.

{phang}
{cmd:update} and {cmd:replace}
    both perform an update merge rather than a standard merge.
    In a standard merge, the data in the master are
    the authority and inviolable.  For example, if the master
    and using datasets both contain a variable {cmd:age}, then
    matched observations will contain values from the master
    dataset, while unmatched observations will contain values
    from their respective datasets.

{pmore}
    If {cmd:update} is specified, then matched observations will update missing
    values from the master dataset with values from the using dataset.
    Nonmissing values in the master dataset will be unchanged.

{pmore}
    If {cmd:replace} is specified, then matched observations will contain
    values from the using dataset, unless the value in the using dataset
    is missing. 

{pmore}
    Specifying either {cmd:update} or {cmd:replace} affects the meanings of the
    match codes. See
    {mansection D mergeRemarksTreatmentofoverlappingvariables:{it:Treatment of overlapping variables}}
    in {bf:[D] merge} for details.

{phang}
{cmd:noreport}
    specifies that {cmd:merge2} not present its summary table of
    match results.

{phang}
{opt force} allows string/numeric variable type mismatches, resulting in
missing values from the using dataset.  If omitted, {cmd:merge2} issues an
error; if specified, {cmd:merge2} issues a warning.


{marker examples}{...}
{title:Examples}

    {hline}
{pstd}Perform 1:1 match merge2, using exactly the same syntax as merge{p_end}
{phang2}{cmd:. webuse autosize}{p_end}
{phang2}{cmd:. merge2 1:1 make using http://www.stata-press.com/data/r12/autoexpense}{p_end}
{phang2}{cmd:. list}{p_end}

    {hline}
{pstd}Perform 1:1 match merge2, where master key is called make_master and using key is called make{break}
{phang2}{cmd:. webuse autosize, clear}{p_end}
{phang2}{cmd:. rename make make_master}{p_end}
{phang2}{cmd:. merge2 1:1 make_master using http://www.stata-press.com/data/r12/autoexpense, using_keys(make)}{p_end}
{phang2}{cmd:. tab _merge}{p_end}
{phang2}{cmd:. list}{p_end}
